# Copyright (c) Meta Platforms, Inc. and affiliates.
# All rights reserved.

# This source code is licensed under the license found in the
# LICENSE file in the root directory of this source tree.
# --------------------------------------------------------
# References:
# DeiT: https://github.com/facebookresearch/deit
# BEiT: https://github.com/microsoft/unilm/tree/master/beit
# --------------------------------------------------------

import builtins
import datetime
import os
import time
from collections import defaultdict, deque
from pathlib import Path

import torch
import torch.distributed as dist
from torch import inf


class SmoothedValue(object):
    """
    跟踪一系列数值，并提供在滑动窗口内或全局序列平均值上的平滑值访问。

    参数：
        window_size (int): 平滑的窗口大小。仅在计算窗口内的平均值时使用。
        fmt (str): 打印格式，默认格式为 "{median:.4f} ({global_avg:.4f})"。
    """

    def __init__(self, window_size=20, fmt=None):
        # 初始化方法，接受窗口大小和格式
        if fmt is None:
            fmt = "{median:.4f} ({global_avg:.4f})"
        self.deque = deque(maxlen=window_size)  # 使用 deque 存储历史数值，限制长度为 window_size
        self.total = 0.0  # 总值，用于计算全局平均值
        self.count = 0  # 计数器，统计更新次数
        self.fmt = fmt  # 设置输出格式

    def update(self, value, n=1):
        """
        更新平滑值，添加一个新值并更新总和和计数器。

        参数：
            value (float): 新的数值
            n (int): 新值的个数，默认为 1
        """
        self.deque.append(value)  # 将新值添加到 deque 中
        self.count += n  # 更新计数器
        self.total += value * n  # 更新总和

    def synchronize_between_processes(self):
        """
        在多进程训练时同步进程间的统计信息（如 total 和 count）。
        注意：不同步 deque（历史值）。
        """
        if not is_dist_avail_and_initialized():  # 检查分布式是否可用
            return
        t = torch.tensor([self.count, self.total], dtype=torch.float64, device='cuda')
        dist.barrier()  # 同步所有进程
        dist.all_reduce(t)  # 汇总各个进程的 count 和 total
        t = t.tolist()
        self.count = int(t[0])  # 更新总 count
        self.total = t[1]  # 更新总 total

    @property
    def median(self):
        """
        返回 deque 中数值的中位数
        """
        d = torch.tensor(list(self.deque))
        return d.median().item()

    @property
    def avg(self):
        """
        返回 deque 中数值的平均值
        """
        d = torch.tensor(list(self.deque), dtype=torch.float32)
        return d.mean().item()

    @property
    def global_avg(self):
        """
        返回全局平均值（total / count）
        """
        return self.total / self.count

    @property
    def max(self):
        """
        返回 deque 中数值的最大值
        """
        return max(self.deque)

    @property
    def value(self):
        """
        返回 deque 中最近添加的值
        """
        return self.deque[-1]

    def __str__(self):
        """
        返回当前 SmoothedValue 对象的字符串表示，包含中位数、全局平均值等
        """
        return self.fmt.format(
            median=self.median,
            avg=self.avg,
            global_avg=self.global_avg,
            max=self.max,
            value=self.value)


class MetricLogger(object):
    """
    用于跟踪和记录各种指标（如损失、准确率等）的工具。
    提供更新、输出和同步功能，用于分布式训练。
    """

    def __init__(self, delimiter="\t"):
        # 初始化方法，接受分隔符参数，用于格式化输出
        self.meters = defaultdict(SmoothedValue)  # 存储各类指标的 SmoothedValue 对象
        self.delimiter = delimiter  # 设置分隔符

    def update(self, **kwargs):
        """
        更新指标的值。

        参数：
            kwargs: 传入的指标名称和对应的数值。
        """
        for k, v in kwargs.items():
            if v is None:
                continue
            if isinstance(v, torch.Tensor):
                v = v.item()  # 转换为标量
            assert isinstance(v, (float, int))
            self.meters[k].update(v)  # 更新相应指标的 SmoothedValue

    def __getattr__(self, attr):
        """
        通过属性访问器提供对指标的访问。
        """
        if attr in self.meters:
            return self.meters[attr]  # 返回对应指标的 SmoothedValue
        if attr in self.__dict__:
            return self.__dict__[attr]
        raise AttributeError("'{}' object has no attribute '{}'".format(
            type(self).__name__, attr))

    def __str__(self):
        """
        将所有的指标以字符串形式返回，格式化输出。
        """
        loss_str = []
        for name, meter in self.meters.items():
            loss_str.append(
                "{}: {}".format(name, str(meter))
            )
        return self.delimiter.join(loss_str)

    def synchronize_between_processes(self):
        """
        在多个进程中同步各个进程的指标。
        """
        for meter in self.meters.values():
            meter.synchronize_between_processes()

    def add_meter(self, name, meter):
        """
        添加新的指标。

        参数：
            name (str): 指标名称
            meter (SmoothedValue): 指标的 SmoothedValue 对象
        """
        self.meters[name] = meter

    def log_every(self, iterable, print_freq, header=None):
        """
        每隔一定次数（print_freq）打印一次日志，并输出训练的相关信息。

        参数：
            iterable: 训练数据集（迭代器）
            print_freq (int): 打印频率
            header (str): 日志的头部信息
        """
        i = 0
        if not header:
            header = ''
        start_time = time.time()
        end = time.time()
        iter_time = SmoothedValue(fmt='{avg:.4f}')
        data_time = SmoothedValue(fmt='{avg:.4f}')
        space_fmt = ':' + str(len(str(len(iterable)))) + 'd'
        log_msg = [
            header,
            '[{0' + space_fmt + '}/{1}]',
            'eta: {eta}',
            '{meters}',
            'time: {time}',
            'data: {data}'
        ]
        if torch.cuda.is_available():
            log_msg.append('max mem: {memory:.0f}')
        log_msg = self.delimiter.join(log_msg)
        MB = 1024.0 * 1024.0
        for obj in iterable:
            data_time.update(time.time() - end)
            yield obj
            iter_time.update(time.time() - end)
            if i % print_freq == 0 or i == len(iterable) - 1:
                eta_seconds = iter_time.global_avg * (len(iterable) - i)
                eta_string = str(datetime.timedelta(seconds=int(eta_seconds)))
                if torch.cuda.is_available():
                    print(log_msg.format(
                        i, len(iterable), eta=eta_string,
                        meters=str(self),
                        time=str(iter_time), data=str(data_time),
                        memory=torch.cuda.max_memory_allocated() / MB))
                else:
                    print(log_msg.format(
                        i, len(iterable), eta=eta_string,
                        meters=str(self),
                        time=str(iter_time), data=str(data_time)))
            i += 1
            end = time.time()
        total_time = time.time() - start_time
        total_time_str = str(datetime.timedelta(seconds=int(total_time)))
        print('{} Total time: {} ({:.4f} s / it)'.format(
            header, total_time_str, total_time / len(iterable)))


def setup_for_distributed(is_master):
    """
    This function disables printing when not in master process
    """
    builtin_print = builtins.print

    def print(*args, **kwargs):
        force = kwargs.pop('force', False)
        force = force or (get_world_size() > 8)
        if is_master or force:
            now = datetime.datetime.now().time()
            builtin_print('[{}] '.format(now), end='')  # print with time stamp
            builtin_print(*args, **kwargs)

    builtins.print = print


def is_dist_avail_and_initialized():
    """
    检查分布式训练是否可用并已初始化。
    """
    if not dist.is_available():
        return False
    if not dist.is_initialized():
        return False
    return True



def get_world_size():
    """
    获取分布式训练中的进程总数（即 world size）。
    如果没有启用分布式训练，返回 1。
    """
    if not is_dist_avail_and_initialized():
        return 1
    return dist.get_world_size()



def get_rank():
    """
    获取当前进程的 rank（在所有进程中的唯一标识）。
    如果没有启用分布式训练，返回 0。
    """
    if not is_dist_avail_and_initialized():
        return 0
    return dist.get_rank()


def is_main_process():
    """
    判断当前进程是否为主进程（rank 为 0 的进程）。
    """
    return get_rank() == 0



def save_on_master(*args, **kwargs):
    """
    仅在主进程上保存模型。此函数用于分布式训练环境，确保只有主进程保存检查点。
    """
    if is_main_process():
        torch.save(*args, **kwargs)



def init_distributed_mode(args):
    """
    初始化分布式训练模式。设置分布式训练的参数，初始化进程组，并设置相应的环境变量。
    根据不同的环境（如 ITP, SLURM 或其他）获取 rank、world size 和 GPU 设备信息。

    参数：
        args: 启动训练时的命令行参数
    """
    if args.dist_on_itp:
        # ITP 环境下的初始化
        args.rank = int(os.environ['OMPI_COMM_WORLD_RANK'])
        args.world_size = int(os.environ['OMPI_COMM_WORLD_SIZE'])
        args.gpu = int(os.environ['OMPI_COMM_WORLD_LOCAL_RANK'])
        args.dist_url = "tcp://%s:%s" % (os.environ['MASTER_ADDR'], os.environ['MASTER_PORT'])
        os.environ['LOCAL_RANK'] = str(args.gpu)
        os.environ['RANK'] = str(args.rank)
        os.environ['WORLD_SIZE'] = str(args.world_size)
    elif 'RANK' in os.environ and 'WORLD_SIZE' in os.environ:
        # 常规分布式训练
        args.rank = int(os.environ["RANK"])
        args.world_size = int(os.environ['WORLD_SIZE'])
        args.gpu = int(os.environ['LOCAL_RANK'])
    elif 'SLURM_PROCID' in os.environ:
        # SLURM 环境下的初始化
        args.rank = int(os.environ['SLURM_PROCID'])
        args.gpu = args.rank % torch.cuda.device_count()
    else:
        # 非分布式环境
        print('Not using distributed mode')
        setup_for_distributed(is_master=True)  # hack
        args.distributed = False
        return

    args.distributed = True

    torch.cuda.set_device(args.gpu)
    args.dist_backend = 'nccl'
    print('| distributed init (rank {}): {}, gpu {}'.format(
        args.rank, args.dist_url, args.gpu), flush=True)
    torch.distributed.init_process_group(backend=args.dist_backend, init_method=args.dist_url,
                                         world_size=args.world_size, rank=args.rank)
    torch.distributed.barrier()  # 同步所有进程
    setup_for_distributed(args.rank == 0)


class NativeScalerWithGradNormCount:
    """
    AMP (自动混合精度) 的梯度缩放器，包含梯度裁剪、归一化及更新。
    用于在训练过程中进行精度提升和防止梯度爆炸。
    """
    state_dict_key = "amp_scaler"

    def __init__(self):
        # 初始化 GradScaler 对象，用于混合精度训练
        self._scaler = torch.cuda.amp.GradScaler()

    def __call__(self, loss, optimizer, clip_grad=None, parameters=None, create_graph=False, update_grad=True):
        """
        计算梯度并进行缩放，更新优化器。还可以进行梯度裁剪和梯度更新。

        参数：
            loss: 当前批次的损失值
            optimizer: 优化器
            clip_grad: 梯度裁剪阈值（可选）
            parameters: 要计算梯度的模型参数（可选）
            create_graph: 是否创建计算图（用于二阶导数计算）
            update_grad: 是否更新梯度（默认为 True）

        返回：
            norm: 更新后的梯度范数（可选）
        """
        self._scaler.scale(loss).backward(create_graph=create_graph)  # 反向传播，缩放梯度
        if update_grad:
            if clip_grad is not None:
                assert parameters is not None
                self._scaler.unscale_(optimizer)  # 解除优化器的缩放
                norm = torch.nn.utils.clip_grad_norm_(parameters, clip_grad)  # 梯度裁剪
            else:
                self._scaler.unscale_(optimizer)
                norm = get_grad_norm_(parameters)  # 获取梯度范数
            self._scaler.step(optimizer)  # 更新参数
            self._scaler.update()  # 更新缩放因子
        else:
            norm = None
        return norm

    def state_dict(self):
        """返回 GradScaler 的状态字典"""
        return self._scaler.state_dict()

    def load_state_dict(self, state_dict):
        """加载 GradScaler 的状态字典"""
        self._scaler.load_state_dict(state_dict)


def get_grad_norm_(parameters, norm_type: float = 2.0) -> torch.Tensor:
    """
    获取模型参数的梯度范数。

    参数：
        parameters: 要计算梯度范数的模型参数
        norm_type: 使用的范数类型，默认是 L2 范数

    返回：
        梯度范数
    """
    if isinstance(parameters, torch.Tensor):
        parameters = [parameters]
    parameters = [p for p in parameters if p.grad is not None]  # 只考虑有梯度的参数
    norm_type = float(norm_type)
    if len(parameters) == 0:
        return torch.tensor(0.)
    device = parameters[0].grad.device
    if norm_type == inf:
        total_norm = max(p.grad.detach().abs().max().to(device) for p in parameters)  # 使用 L∞ 范数
    else:
        total_norm = torch.norm(torch.stack([torch.norm(p.grad.detach(), norm_type).to(device) for p in parameters]), norm_type)
    return total_norm



def save_model(args, epoch, model, model_without_ddp, optimizer, loss_scaler):
    """
    保存模型的检查点。仅在主进程中保存，并包含模型状态、优化器状态、epoch 信息等。

    参数：
        args: 启动训练时的命令行参数
        epoch: 当前的 epoch 数
        model: 当前的模型
        model_without_ddp: 不包含分布式数据并行的模型
        optimizer: 优化器
        loss_scaler: AMP 的缩放器
    """
    output_dir = Path(args.output_dir)
    epoch_name = str(epoch)
    if loss_scaler is not None:
        checkpoint_paths = [output_dir / ('checkpoint-%s.pth' % epoch_name)]
        for checkpoint_path in checkpoint_paths:
            to_save = {
                'model': model_without_ddp.state_dict(),
                'optimizer': optimizer.state_dict(),
                'epoch': epoch,
                'scaler': loss_scaler.state_dict(),
                'args': args,
            }

            save_on_master(to_save, checkpoint_path)  # 在主进程中保存
    else:
        client_state = {'epoch': epoch}
        model.save_checkpoint(save_dir=args.output_dir, tag="checkpoint-%s" % epoch_name, client_state=client_state)



def load_model(args, model_without_ddp, optimizer, loss_scaler):
    """
    加载模型的检查点。如果需要恢复训练，加载之前保存的模型状态、优化器状态等。

    参数：
        args: 启动训练时的命令行参数
        model_without_ddp: 不包含分布式数据并行的模型
        optimizer: 优化器
        loss_scaler: AMP 的缩放器
    """
    if args.resume:
        if args.resume.startswith('https'):
            checkpoint = torch.hub.load_state_dict_from_url(
                args.resume, map_location='cpu', check_hash=True)
        else:
            checkpoint = torch.load(args.resume, map_location='cpu')
        model_without_ddp.load_state_dict(checkpoint['model'])
        print("Resume checkpoint %s" % args.resume)
        if 'optimizer' in checkpoint and 'epoch' in checkpoint and not (hasattr(args, 'eval') and args.eval):
            optimizer.load_state_dict(checkpoint['optimizer'])
            args.start_epoch = checkpoint['epoch'] + 1
            if 'scaler' in checkpoint:
                loss_scaler.load_state_dict(checkpoint['scaler'])
            print("With optim & sched!")


def all_reduce_mean(x):
    """
    对张量 x 在分布式训练环境中进行 all-reduce 操作，并计算所有进程的平均值。

    参数：
        x: 输入张量

    返回：
        平均值
    """
    world_size = get_world_size()
    if world_size > 1:
        x_reduce = torch.tensor(x).cuda()
        dist.all_reduce(x_reduce)
        x_reduce /= world_size
        return x_reduce.item()
    else:
        return x
